home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / gport.exe / GPORT.DOC < prev    next >
Text File  |  1993-04-09  |  27KB  |  1,164 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.                     Gport
  12.  
  13.                     C Language Game Port Library
  14.  
  15.                     Version 1.01
  16.  
  17.                     1 September 91
  18.  
  19.                     Copyright (c) 1991  Bri Productions
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.                                         1
  63.  
  64.  
  65.  
  66.         Table of Contents
  67.  
  68.  
  69.             Introduction
  70.  
  71.                     General Description.....................3
  72.  
  73.                     Disclaimer..............................3
  74.  
  75.                     Registration............................3
  76.  
  77.                     Contacting the Author...................3
  78.  
  79.                     A typedef...............................3
  80.  
  81.  
  82.             General Functions
  83.  
  84.                     Description.............................4
  85.  
  86.                     GamOpen.................................5
  87.  
  88.                     GamClose................................6
  89.  
  90.                     GamAxis.................................6
  91.  
  92.                     GamAxes.................................7
  93.  
  94.                     GamButton...............................8
  95.  
  96.  
  97.             Calibration Functions
  98.  
  99.                     Description............................10
  100.  
  101.                     GamRawAxis.............................11
  102.  
  103.                     GamCalAxis.............................12
  104.  
  105.                     GamCenter..............................13
  106.  
  107.  
  108.  
  109.             Appendix A - Things to Look Out For............15
  110.  
  111.             Appendix B - Joystick Calibration/Centering....16
  112.  
  113.             Appendix C - Registration Form.................18
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.                                         2
  125.  
  126.  
  127.  
  128.         General Description.
  129.  
  130.         Gport is a C language, high speed, high resolution game port
  131.         library for IBM and compatible computers. Gport is compatible
  132.         with most if not all DOS based C compilers.
  133.  
  134.  
  135.         Some of Gport's features are:
  136.  
  137.         ∙ Timer driven button monitor.
  138.         ∙ Optional joystick calibration.
  139.         ∙ Choice of REAL or MEAN centering modes.
  140.         ∙ Yields higher resolution on faster computers.
  141.         ∙ Constant axis scaling to approximately ±1000.
  142.         ∙ Written in assembly language for optimum speed and efficiency.
  143.  
  144.  
  145.         DISCLAIMER.
  146.  
  147.         Gport is provided AS IS. Bri Productions specifically disclaims
  148.         any and all warranties, expressed or implied, including fitness
  149.         for a particular purpose. Use this product at your own risk.
  150.  
  151.  
  152.         Registration.
  153.  
  154.         Gport is a user supported software product. Distribution of
  155.         this product, unaltered and without charge, is encouraged. If
  156.         you find this product useful, you are encouraged to register
  157.         your copy. This allows Bri Productions to continue to provide
  158.         and support low cost, high quality shareware.
  159.  
  160.         The registration fee is $25.00 US dollars and includes libraries
  161.         for small, medium, compact and large memory models and complete
  162.         source code. A registration form is provided in Appendix C.
  163.  
  164.  
  165.         Contacting the author.
  166.  
  167.         Bri Productions may be contacted by any of the following means:
  168.  
  169.         U.S. mail       -       Bri Productions
  170.                                 P.O.Box 7121
  171.                                 Fremont, CA 94537-7121
  172.         Phone           -       (510) 794-0616
  173.         CompuServe      -       76635,2246
  174.  
  175.         CompuServe is a trademark of CompuServe Inc.
  176.  
  177.  
  178.         A typedef.
  179.  
  180.         You will see the data type 'byte' throughout the Gport library.
  181.         This is a typedef defined in gport.h. Byte is an unsigned
  182.         character used for byte size values.
  183.  
  184.  
  185.  
  186.  
  187.                                         3
  188.  
  189.  
  190.  
  191.         General functions
  192.  
  193.         There are two functions that are required before other game
  194.         port functions can be called. They are GamOpen() and GamClose().
  195.         GamOpen() initializes the game port and installs an interrupt
  196.         handler for monitoring the buttons. GamClose() releases the
  197.         interrupt handler. Failing to call GamClose() prior to the
  198.         program's termination will most certainly cause an operating
  199.         system crash.
  200.  
  201.         GamAxis() and GamAxes() fetches the position(s) of one or
  202.         more joystick axes. A full up or right joystick returns a value
  203.         of approximately +1000 and full down or left returns a value of
  204.         approximately -1000. GamButton() fetches the status of the game
  205.         port's buttons. Information on a button pressed since the last
  206.         call to GamButton() as well as a presently pressed is available.
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.                                         4
  250.  
  251.  
  252.  
  253.         ----------------------------------------------------------------
  254.         GamOpen
  255.         ----------------------------------------------------------------
  256.  
  257.         Function
  258.  
  259.                 Initializes the game port and installs the interrupt
  260.                 handler.
  261.  
  262.  
  263.         Syntax
  264.  
  265.                 #include "gport.h"
  266.                 int GamOpen(void);
  267.  
  268.  
  269.         Remarks
  270.  
  271.                 GamOpen initializes the game port. If an axis is found to
  272.                 be valid, it's corresponding bit is set in the returned
  273.                 status word. After a call to GamOpen, a subsequent call
  274.                 to GamClose is required. Failure to do so will most
  275.                 definitely cause the operating system to crash.
  276.  
  277.  
  278.         Return Value
  279.  
  280.                 GamOpen returns a valid axis status word. The bits/values
  281.                 are defined as follows:
  282.  
  283.                         JAX_VAL  (0x1) - Joystick A, x axis valid
  284.                         JAY_VAL  (0x2) - Joystick A, y axis valid
  285.                         JA_VAL   (0x3) - Joystick A, both axes valid
  286.                         JBX_VAL  (0x4) - Joystick B, x axis valid
  287.                         JBY_VAL  (0x8) - Joystick B, y axis valid
  288.                         JB_VAL   (0xC) - Joystick B, both axes valid
  289.  
  290.  
  291.         See also
  292.  
  293.                 GamClose
  294.  
  295.  
  296.         Example
  297.  
  298.                 Attempt to open the game port and check Joystick A.
  299.  
  300.                 {
  301.                 int valid_axes;
  302.  
  303.                    valid_axes = GamOpen();
  304.                    if((valid_axis & JA_VAL) == JA_VAL)
  305.                    {
  306.                       ...Joystick A OK
  307.  
  308.                    }
  309.                 }
  310.  
  311.                                         5
  312.  
  313.  
  314.  
  315.         ----------------------------------------------------------------
  316.         GamClose
  317.         ----------------------------------------------------------------
  318.  
  319.         Function
  320.  
  321.                 Releases the interrupt handler.
  322.  
  323.  
  324.         Syntax
  325.  
  326.                 #include "gport.h"
  327.                 void GamClose(void);
  328.  
  329.  
  330.         Remarks
  331.  
  332.                 After a call to GamOpen, a subsequent call to GamClose
  333.                 is required. Failure to do so will most definitely cause
  334.                 the operating system to crash.
  335.  
  336.  
  337.         See also
  338.  
  339.                 GamOpen
  340.  
  341.  
  342.         Example
  343.  
  344.                 Close the game port prior to terminating.
  345.  
  346.                 {
  347.  
  348.                   ...closing code
  349.  
  350.                   GamClose();
  351.                   exit(0)
  352.  
  353.                 }
  354.  
  355.  
  356.  
  357.  
  358.         ----------------------------------------------------------------
  359.         GamAxis
  360.         ----------------------------------------------------------------
  361.  
  362.         Function
  363.  
  364.                 Gets the coordinate of a joystick axis.
  365.  
  366.  
  367.         Syntax
  368.  
  369.                 #include "gport.h"
  370.                 signed GamAxis(byte axis);
  371.  
  372.  
  373.                                         6
  374.  
  375.  
  376.  
  377.         Parameters
  378.  
  379.                 axis  - Constant that defines which axis to get the
  380.                         coordinate of. Possibilities are:
  381.  
  382.                            JAX  (0) - Joystick A, X axis
  383.                            JAY  (1) - Joystick A, Y axis
  384.                            JBX  (2) - Joystick B,